<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Synopsis</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../boost_lexical_cast.html" title="Chapter 18. Boost.Lexical_Cast 1.0">
<link rel="prev" href="examples.html" title="Examples">
<link rel="next" href="frequently_asked_questions.html" title="Frequently Asked Questions">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
<td align="center"><a href="../../../index.html">Home</a></td>
<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="examples.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boost_lexical_cast.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="frequently_asked_questions.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="boost_lexical_cast.synopsis"></a><a class="link" href="synopsis.html" title="Synopsis">Synopsis</a>
</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="synopsis.html#boost_lexical_cast.synopsis.lexical_cast">lexical_cast</a></span></dt>
<dt><span class="section"><a href="synopsis.html#boost_lexical_cast.synopsis.bad_lexical_cast">bad_lexical_cast</a></span></dt>
<dt><span class="section"><a href="synopsis.html#boost_lexical_cast.synopsis.try_lexical_convert">try_lexical_convert</a></span></dt>
</dl></div>
<p>
      Library features defined in <a href="../../../boost/lexical_cast.hpp" target="_top">boost/lexical_cast.hpp</a>:
</p>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span>
<span class="special">{</span>
    <span class="keyword">class</span> <span class="identifier">bad_lexical_cast</span><span class="special">;</span>

    <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Target</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Source</span><span class="special">&gt;</span>
      <span class="identifier">Target</span> <span class="identifier">lexical_cast</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Source</span><span class="special">&amp;</span> <span class="identifier">arg</span><span class="special">);</span>

    <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Target</span><span class="special">&gt;</span>
      <span class="identifier">Target</span> <span class="identifier">lexical_cast</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">AnyCharacterType</span><span class="special">*</span> <span class="identifier">chars</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">count</span><span class="special">);</span>

    <span class="keyword">namespace</span> <span class="identifier">conversion</span>
    <span class="special">{</span>
        <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Target</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Source</span><span class="special">&gt;</span>
            <span class="keyword">bool</span> <span class="identifier">try_lexical_convert</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Source</span><span class="special">&amp;</span> <span class="identifier">arg</span><span class="special">,</span> <span class="identifier">Target</span><span class="special">&amp;</span> <span class="identifier">result</span><span class="special">);</span>

        <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">AnyCharacterType</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Target</span><span class="special">&gt;</span>
            <span class="keyword">bool</span> <span class="identifier">try_lexical_convert</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">AnyCharacterType</span><span class="special">*</span> <span class="identifier">chars</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">count</span><span class="special">,</span> <span class="identifier">Target</span><span class="special">&amp;</span> <span class="identifier">result</span><span class="special">);</span>

    <span class="special">}</span> <span class="comment">// namespace conversion</span>
<span class="special">}</span> <span class="comment">// namespace boost</span>
</pre>
<p>
    </p>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_lexical_cast.synopsis.lexical_cast"></a><a class="link" href="synopsis.html#boost_lexical_cast.synopsis.lexical_cast" title="lexical_cast">lexical_cast</a>
</h3></div></div></div>
<p>
</p>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Target</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Source</span><span class="special">&gt;</span>
  <span class="identifier">Target</span> <span class="identifier">lexical_cast</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Source</span><span class="special">&amp;</span> <span class="identifier">arg</span><span class="special">);</span>
</pre>
<p>
        Returns the result of streaming arg into a standard library string-based
        stream and then out as a Target object. Where Target is either <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code>
        or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstring</span></code>, stream extraction takes the whole
        content of the string, including spaces, rather than relying on the default
        <code class="computeroutput"><span class="keyword">operator</span><span class="special">&gt;&gt;</span></code>
        behavior. If the conversion is unsuccessful, a <code class="computeroutput"><span class="identifier">bad_lexical_cast</span></code>
        exception is thrown.
      </p>
<p>
</p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Target</span><span class="special">&gt;</span>
  <span class="identifier">Target</span> <span class="identifier">lexical_cast</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">AnyCharacterType</span><span class="special">*</span> <span class="identifier">chars</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">count</span><span class="special">);</span>
</pre>
<p>
        Takes an array of <code class="computeroutput"><span class="identifier">count</span></code> characters
        as input parameter and streams them out as a Target object. If the conversion
        is unsuccessful, a <code class="computeroutput"><span class="identifier">bad_lexical_cast</span></code>
        exception is thrown. This call may be useful for processing nonzero terminated
        array of characters or processing just some part of character array.
      </p>
<p>
        The requirements on the argument and result types for both functions are:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            Source is OutputStreamable, meaning that an <code class="computeroutput"><span class="keyword">operator</span><span class="special">&lt;&lt;</span></code> is defined that takes a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span></code> or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wostream</span></code>
            object on the left hand side and an instance of the argument type on
            the right.
          </li>
<li class="listitem">
            Target is InputStreamable, meaning that an <code class="computeroutput"><span class="keyword">operator</span><span class="special">&gt;&gt;</span></code> is defined that takes a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">istream</span></code> or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wistream</span></code>
            object on the left hand side and an instance of the result type on the
            right.
          </li>
<li class="listitem">
            Target is CopyConstructible [20.1.3].
          </li>
<li class="listitem">
            Target is DefaultConstructible, meaning that it is possible to default-initialize
            an object of that type [8.5, 20.1.4].
          </li>
</ul></div>
<p>
        The character type of the underlying stream is assumed to be <code class="computeroutput"><span class="keyword">char</span></code> unless either the <code class="computeroutput"><span class="identifier">Source</span></code>
        or the <code class="computeroutput"><span class="identifier">Target</span></code> requires wide-character
        streaming, in which case the underlying stream uses <code class="computeroutput"><span class="keyword">wchar_t</span></code>.
        Following types also can use <code class="computeroutput"><span class="keyword">char16_t</span></code>
        or <code class="computeroutput"><span class="keyword">char32_t</span></code> for wide-character
        streaming:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            Single character: <code class="computeroutput"><span class="keyword">char16_t</span></code>,
            <code class="computeroutput"><span class="keyword">char32_t</span></code>
          </li>
<li class="listitem">
            Arrays of characters: <code class="computeroutput"><span class="keyword">char16_t</span>
            <span class="special">*</span></code>, <code class="computeroutput"><span class="keyword">char32_t</span>
            <span class="special">*</span></code>, <code class="computeroutput"><span class="keyword">const</span>
            <span class="keyword">char16_t</span> <span class="special">*</span></code>,
            <code class="computeroutput"><span class="keyword">const</span> <span class="keyword">char32_t</span>
            <span class="special">*</span></code>
          </li>
<li class="listitem">
            Strings: <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_string</span></code>, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">containers</span><span class="special">::</span><span class="identifier">basic_string</span></code>
          </li>
<li class="listitem">
            <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">iterator_range</span><span class="special">&lt;</span><span class="identifier">WideCharPtr</span><span class="special">&gt;</span></code>,
            where <code class="computeroutput"><span class="identifier">WideCharPtr</span></code> is
            a pointer to wide-character or pointer to const wide-character
          </li>
<li class="listitem">
            <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">CharT</span><span class="special">,</span> <span class="identifier">N</span><span class="special">&gt;</span></code>
            and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="identifier">CharT</span><span class="special">,</span> <span class="identifier">N</span><span class="special">&gt;</span></code>,
            <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="identifier">CharT</span><span class="special">,</span> <span class="identifier">N</span><span class="special">&gt;</span></code> and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">array</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="identifier">CharT</span><span class="special">,</span> <span class="identifier">N</span><span class="special">&gt;</span></code>
          </li>
</ul></div>
<div class="important"><table border="0" summary="Important">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../doc/src/images/important.png"></td>
<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top">
<p>
          Many compilers and runtime libraries fail to make conversions using new
          Unicode characters. Make sure that the following code compiles and outputs
          nonzero values, before using new types:
</p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span>
    <span class="special">&lt;&lt;</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">lexical_cast</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">u32string</span><span class="special">&gt;(</span><span class="number">1.0</span><span class="special">).</span><span class="identifier">size</span><span class="special">()</span>
    <span class="special">&lt;&lt;</span> <span class="string">"  "</span>
    <span class="special">&lt;&lt;</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">lexical_cast</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">u16string</span><span class="special">&gt;(</span><span class="number">1.0</span><span class="special">).</span><span class="identifier">size</span><span class="special">();</span>
</pre>
<p>
        </p>
</td></tr>
</table></div>
<p>
        Where a higher degree of control is required over conversions, <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">stringstream</span></code>
        and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wstringstream</span></code> offer a more appropriate
        path. Where non-stream-based conversions are required, <code class="computeroutput"><span class="identifier">lexical_cast</span></code>
        is the wrong tool for the job and is not special-cased for such scenarios.
      </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_lexical_cast.synopsis.bad_lexical_cast"></a><a class="link" href="synopsis.html#boost_lexical_cast.synopsis.bad_lexical_cast" title="bad_lexical_cast">bad_lexical_cast</a>
</h3></div></div></div>
<p>
</p>
<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">bad_lexical_cast</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">bad_cast</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
    <span class="special">...</span> <span class="comment">// same member function interface as std::exception</span>
<span class="special">};</span>
</pre>
<p>
        Exception used to indicate runtime lexical_cast failure.
      </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_lexical_cast.synopsis.try_lexical_convert"></a><a class="link" href="synopsis.html#boost_lexical_cast.synopsis.try_lexical_convert" title="try_lexical_convert">try_lexical_convert</a>
</h3></div></div></div>
<p>
        <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">lexical_cast</span></code> remains the main interface
        for lexical conversions. It must be used by default in most cases. However
        some developers wish to make their own conversion functions, reusing all
        the optimizations of the <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">lexical_cast</span></code>.
        That's where the <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">conversion</span><span class="special">::</span><span class="identifier">try_lexical_convert</span></code> function steps in.
      </p>
<p>
        <code class="computeroutput"><span class="identifier">try_lexical_convert</span></code> returns
        <code class="computeroutput"><span class="keyword">true</span></code> if conversion succeeded,
        otherwise returns <code class="computeroutput"><span class="keyword">false</span></code>. If
        conversion failed and <code class="computeroutput"><span class="keyword">false</span></code>
        was returned, state of <code class="computeroutput"><span class="identifier">result</span></code>
        output variable is undefined.
      </p>
<p>
        Actually, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">lexical_cast</span></code> is implemented using <code class="computeroutput"><span class="identifier">try_lexical_convert</span></code>:
</p>
<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Target</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Source</span><span class="special">&gt;</span>
<span class="keyword">inline</span> <span class="identifier">Target</span> <span class="identifier">lexical_cast</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Source</span> <span class="special">&amp;</span><span class="identifier">arg</span><span class="special">)</span>
<span class="special">{</span>
    <span class="identifier">Target</span> <span class="identifier">result</span><span class="special">;</span>

    <span class="keyword">if</span> <span class="special">(!</span><span class="identifier">conversion</span><span class="special">::</span><span class="identifier">try_lexical_convert</span><span class="special">(</span><span class="identifier">arg</span><span class="special">,</span> <span class="identifier">result</span><span class="special">))</span>
        <span class="keyword">throw</span> <span class="identifier">bad_lexical_cast</span><span class="special">();</span>

    <span class="keyword">return</span> <span class="identifier">result</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
      </p>
<p>
        <code class="computeroutput"><span class="identifier">try_lexical_convert</span></code> relaxes
        the CopyConstructible and DefaultConstructible requirements for <code class="computeroutput"><span class="identifier">Target</span></code> type. Following requirements for
        <code class="computeroutput"><span class="identifier">Target</span></code> and <code class="computeroutput"><span class="identifier">Source</span></code> remain:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            Source must be OutputStreamable, meaning that an <code class="computeroutput"><span class="keyword">operator</span><span class="special">&lt;&lt;</span></code> is defined that takes a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span></code> or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wostream</span></code>
            object on the left hand side and an instance of the argument type on
            the right.
          </li>
<li class="listitem">
            Target must be InputStreamable, meaning that an <code class="computeroutput"><span class="keyword">operator</span><span class="special">&gt;&gt;</span></code> is defined that takes a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">istream</span></code> or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">wistream</span></code>
            object on the left hand side and an instance of the result type on the
            right.
          </li>
</ul></div>
</div>
</div>
<div class="copyright-footer">Copyright © 2000-2005 Kevlin Henney<br>Copyright © 2006-2010 Alexander Nasonov<br>Copyright © 2011-2025 Antony Polukhin<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="examples.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../boost_lexical_cast.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="frequently_asked_questions.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
